home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
EnigmA Amiga Run 1995 November
/
EnigmA AMIGA RUN 02 (1995)(G.R. Edizioni)(IT)[!][issue 1995-11][Skylink CD].iso
/
earcd
/
util
/
text
/
proged1.lha
/
InstallProgED
/
sources
/
DevManual
Wrap
Text File
|
1995-09-02
|
34KB
|
1,401 lines
-----------------------------------------------
ProgED V1.0 by Giovanni Lambiase (C) 1995
Note per i programmatori
-----------------------------------------------
-------------------------
1. Strutture principali
-------------------------
In questo paragrafo descriveremo tutte le strutture utili per un
utente che indenta scrivere un cliente API. Le strutture PEDWindow e Prefs
descrivono, rispettivamente, le finestre aperte dal ProgED e le preferenze
globali. Seguono altre strutture più piccole ma non meno importanti, come
la struttura che definisce le linee del testo o i programmi interni
(creati dal pannello di programmazione del ProgED). Il commento ad ogni
campo inizia con i caratteri "^--" ).
struct PEDWindow
{
struct Window *Window;
^-- Puntatore alla finestra intuition. Se la finestra è chiusa
(vedi comando interno FREEZE) vale NULL.
struct Gadget *GadgetScrollX,
*GadgetScrollY,
*GadgetUpArrow,
*GadgetDownArrow,
*GadgetLeftArrow,
*GadgetRightArrow;
^-- Puntatori ai gadget di scorrimento e alle relative frecce.
struct Image *ImageUpArrow,
*ImageDownArrow,
*ImageLeftArrow,
*ImageRightArrow;
^-- Immagini delle quattro frecce attaccate ai gadget di scroll.
int OldSx,
OldSy,
^-- Ascissa (colonna) e ordinata (linea) del primo carattere in alto
a sinistra nella finestra PRECEDENTI quelle attuali. Questi valori
non considerano i fold precedenti che vengono considerati come una
singola linea.
Sx,
Sy;
^-- Ascissa (colonna) e ordinata (linea) del primo carattere in alto
a sinistra nella finestra ATTUALI. Questi valori non considerano
i fold precedenti che vengono considerati come una singola linea.
struct Line *FirstLine,
*LastLine;
^-- Puntatore alla prima ed alla ultima linea del testo.
LONG MaxCol,
^-- Copia di Prefs.MaxCol (Num. max di colonne nel testo).
NumCol,
^-- Num. di colonne nella finestra (larghezza in caratteri).
MaxLine,
^-- Num. di linee nel testo (non tiene conto dei fold).
NumLine;
^-- Num. di linee nella finestra (altezza in linee).
ULONG Size;
^-- Dimensione in byte del testo in memoria.
WORD Left,
Top,
Width,
Height;
^-- Variabili temporanee. Mantengono le dimensioni e la posizione
della finestra mentre è chiusa.
WORD ZoomInfo[4];
^-- Array relativo al gadget Zoom di intuition.
char FileName[200];
^-- Nome del file (completo) caricato in memoria.
char Title[200];
^-- In questa zona ProgED costruisce il titolo della finestra.
LONG CursorCol;
LONG CursorLine;
^-- Posizione del cursore nel testo (colonna/linea). Non tiene
conto dei fold.
LONG LastCursorCol;
^-- Ultima colonna in cui abbiamo scritto qualcosa.
struct Line *Line;
^-- Puntatore alla linea su cui si trova il cursore.
UWORD RealNumCol;
^-- Num colonne reali (numero di bytes,un TAB è pari ad 1).
UWORD LogicNumCol;
^-- Num colonne logiche (tiene conto degli spazi relativi ai TAB).
UWORD FWidth,
FHeight,
^-- Larghezza e altezza (in pixel) del font utilizzato.
FBase,
^-- Baseline del font utilizzato.
WOffsetX,
WOffsetY;
^-- Offset X ed Y della finestra (dovuto ai bordi sup. e sinistro).
struct RastPort *RP;
^-- Rastport della finestra (Window->RPort).
UBYTE Ins;
^-- TRUE=modo inserimento,FALSE=modo overwrite.
UBYTE MLine,
^-- TRUE=blocco con opzione LINE, FALSE=altrimenti.
Block;
^-- Tipo blocco: NO_SEL,BLOCK_SEL,COLBLOCK_SEL (vedi file "Ped.h").
LONG BlockLine,
BlockCol;
^-- Inizio blocco marcato (linea e colonna).
ULONG Changes;
^-- Cambi dall'ultimo salvataggio.
struct Event *Events;
^-- Puntatore ad un array di strutture Events. Ogni struttura
mantiene un evento per la coda di UNDO/REDO. Il numero di
strutture è dato nel successivo campo UndoLevels.
LONG LastEvent;
^-- Ultimo evento nella coda.
ULONG NumEvent,
^-- Numero di eventi nella coda.
NumRedo,
^-- Numero di REDO possibili.
UndoLevels;
^-- Lunghezza della coda.
char *CuttedLine;
^-- Clipboard linea (vedi comando LINE CUT).
struct Marker Marker[MAXMARKER];
^-- Vettori di marker. Ogni marker detiene una posizione nel testo.
struct Folder *Folder;
^-- Puntatore ad una lista di folder. Ogni struttura mantiene le
informazioni relative ad un fold.
int LinesFolded;
^-- Numero di linee chiuse nei vari fold.
int NumFolds;
^-- Numero totale di fold.
UBYTE Frozen;
^-- TRUE=finestra chiusa, FALSE=aperta.
ULONG Locked;
^-- Se >0 la finestra è bloccata dagli handler.
ULONG AutoSave;
^-- Contatore autosave (in secondi). Decresce fino a 0.
struct Line *OldLine;
UBYTE *LineBuffer,
*Pun,
InsLine,
Warn;
^-- Dati utili SOLO durante il load dal PED_DISK. Non manipolare.
UBYTE OldKeys[MAXTEMPLATE];
UBYTE PunOldKeys;
^-- Dati utili per i template (ricordano gli ultimi tasti battuti).
struct DateStamp DateStamp;
^-- Data ultima modifica (utile per gli handler).
struct PEDWindow *NextWindow;
^-- LINK alla prossima finestra del ProgED.
ULONG UserData[16];
^-- Dati utente. Se hai bisogno di memorizzare dati per ogni
finestra utilizza questi campi.
}
struct Prefs
{
ULONG ScreenMode;
UWORD ScreenWidth;
UWORD ScreenHeight;
UWORD ScreenOverscanType;
UBYTE ScreenDepth;
UBYTE ScreenAutoScroll;
^-- Caratteristiche dello schermo del ProgED: DisplayID,larghezza,
altezza,tipo overscan,profondità,flag autoscroll.
UWORD ScreenColors[MAXCOLOR];
^-- Primi MAXCOLOR colori dello schermo. Tali colori vengono
memorizzati e salvati da ProgED.
char ScreenFontName[MAXFONTNAM+1];
UWORD ScreenFontSize;
^-- Nome e dimensione del font per lo schermo.
char MenuFontName[MAXFONTNAM+1];
UWORD MenuFontSize;
^-- Nome e dimensione del font per i menù.
char TextFontName[MAXFONTNAM+1];
UWORD TextFontSize;
^-- Nome e dimensione del font per i testi.
char GadgetFontName[MAXFONTNAM+1];
UWORD GadgetFontSize;
^-- Nome e dimensione del font per i gadget. ATTENZIONE solo
font di dimensione 8 !!!!!!!!!!!!!!!
UWORD MaxCol;
^-- Numero massimo di colonne per i testi. Ogni finestra, all'apertura,
copia nel suo omonimo campo questo valore.
UBYTE AltStep;
^-- Salto righe quando si utilizza il comando UP STEP (o DOWN STEP).
UBYTE Tab;
^-- Dimensione TAB in caratteri.
UBYTE LeftBorder;
UBYTE RightBorder;
UBYTE TopBorder;
UBYTE BottomBorder;
^-- Bordi oltre il quale il cursore provoca uno scroll.
UBYTE UseKeyWordColors;
^-- TRUE=attiva l'uso dei colori per le parole chiavi,FALSE=disabilita.
UBYTE KeyAlpha[256];
^-- NON MANIPOLARE!!!!!!!!!!!!!!!!!!!!!! Grazie.
char **KeyWord;
^-- Puntatore al vettore di (char *) contenente le parole.
int NumKeyWord;
^-- Numero di parole nel vettore.
char GestColorOff,
GestColorOn;
^-- Caratteri di disattivazione ed attivazione della gestione.
UBYTE UseCommentColors;
^-- TRUE=Attiva l'uso dei colori per i commenti,FALSE=disabilita.
UWORD CheckColorLines;
^-- Max num. di linee di un commento (0=senza limite).
UBYTE Comment1Pen,
^-- Penna da utilizzare per i commenti tra più linee.
Comment2Pen;
^-- Penna da utilizzare per i commenti fino a fine linea.
char Comment1On[MAXCOMMENT+1],
Comment1Off[MAXCOMMENT+1],
^-- Stringhe iniziali e finali dei commenti su più linee.
Comment2On[MAXCOMMENT+1];
^-- Stringa iniziale dei commenti fino a fine linea.
UBYTE BackPen;
^-- Penna sfondo schermo.
UBYTE PaperPen;
^-- Penna carta (sfondo finestre).
UBYTE DefTextPen;
^-- Penna testo.
UBYTE PaperBlockPen;
^-- Penna blocchi marcati.
UWORD ScreenPens[13];
^-- Penne intuition dello schermo del ProgED.
UBYTE Clipboard;
^-- Clipboard standard.
UBYTE EraseRight;
^-- TRUE=attiva cancellazione spazi e TAB a fine linea.
UBYTE ShowCursorPos;
^-- TRUE=Mostra la posizione (linea e colonna) del cursore nella
barra del titolo della finestra.
UBYTE ShowPathName;
^-- TRUE=Mostra il path completo del file,FALSE=solo il nome.
UBYTE AutoArrangeVer;
^-- TRUE=Arrangia verticalmente le finestre. Questo flag è
mutuamente esclusivo col successivo.
UBYTE AutoArrangeHor;
^-- TRUE=Arrangia orizzontalmente le finestre. Questo flag è
mutuamente esclusivo col successivo.
UBYTE Favourite;
^-- TRUE=Favorisci la finestra attiva dandole mezzo schermo.
UBYTE UseSetDefPubScr;
^-- TRUE=Setta lo schermo del ProgED come schermo pubblico.
UBYTE UseClock;
^-- TRUE=Attiva l'orologio sullo schermo del ProgED.
UBYTE Backup;
^-- TRUE=Crea un backup ad ogni salvataggio.
UBYTE Save;
^-- TRUE=Salvataggio sicuro,FALSE=normale.
UBYTE SaveRefs;
^-- TRUE=Salva,insieme al file, i riferimenti contenuti nel file
stesso.
UBYTE UnfoldOnGotoMarker;
UBYTE UnfoldOnGotoLine;
UBYTE UnfoldOnGotoByte;
UBYTE UnfoldOnGotoScan;
^-- TRUE=Effettua un unfold quando il ProgED salta ad una linea dopo:
1) un salto ad un marker, 2) un salto ad una linea, 3) un salto
ad un byte, 4) un salto ad un riferimento
UBYTE BlankBorders;
^-- TRUE=Elimina i bordi degli schermi (rendili neri).
UBYTE AutoFold;
^-- TRUE=Auto-fold al caricamento.
char SearchFoldFileName[MAXFOLDFUNCNAME+1];
^-- Nome della funzione di ricerca dei fold.
LONG DefBits;
^-- Bits da dare ai file salvati (bisogna effettuare uno XOR con
0x000F prima di effettuare l'operazione).
char DefComment[MAXCOMMENT2+1];
^-- Commento da dare ai file salvati.
UBYTE CreateIcons;
^-- TRUE=Crea icone per i file salvati.
UBYTE UseKeyWordInd;
^-- TRUE=Abilita l'indentazione automatica.
char **KeyWordInd;
^-- Puntatore ad un vettore di parole. Ogni parola termina con uno
dei caratteri IND_xxx che specifica il tipo di indentazione.
int NumKeyWordInd;
^-- Numero di parole nel vettore.
UWORD IndJump;
^-- Colonne per livello d'indentazione.
UBYTE SeparateItems;
^-- TRUE=Separa i menù con una barra.
struct MyMenu *Menu;
^-- Puntatore ad una lista che definisce i menù.
char HelpFile[MAXFILENAME+1];
^-- Nome file della guida per i menù.
struct MyKey *Key;
^-- Puntatore ad una lista che definisce i tasti.
UBYTE UseAppIcon;
^-- TRUE=Mostra la AppIcon quando sei iconificato.
UBYTE UseMenuItem;
^-- TRUE=Appendi un item al menù "Strumenti" del WB quando sei
iconificato.
UBYTE UseAutoSave;
^-- TRUE=Attiva autosalvataggio.
UWORD MinAutoSave;
^-- Numero di minuti tra gli autosave.
UBYTE AutoReLoad;
^-- TRUE=Ricarica, alla partenza, tutti i testi che erano in
memoria nella sessione precedente.
UBYTE MouseBlanker;
^-- TRUE=Attiva il mouseblanker.
UBYTE FastLoad;
^-- TRUE=Attiva il caricamento veloce,FALSE=normale.
char **APIClients;
^-- Puntatore ad un vettore di (char *). Ogni stringa è il nome
(su disco) di un cliente API.
int NumAPIClients;
^-- Numero di stringhe nel vettore precedente (numero clienti API).
char StartUpMacro[MAXSTARTUPMACRO];
^-- Macro REXX iniziale.
char PreIconifyMacro[MAXSTARTUPMACRO];
^-- Macro REXX pre-iconificazione.
char PostIconifyMacro[MAXSTARTUPMACRO];
^-- Macro REXX post-iconificazione.
struct MyScan *Scan;
^-- Puntatore ad una lista contenente gli scanner attualmente
caricati.
struct MyTemplate *Template;
^-- Puntatore ad una lista contenente i template.
UBYTE UseTemplate;
^-- TRUE=Attiva gestione dei template.
UBYTE UseRightGadget;
^-- TRUE=Attiva il gadget di scrolling destro.
UBYTE UseBottomGadget;
^-- TRUE=Attiva il gadget di scrolling inferiore.
LONG LeftExtraSpace,
RightExtraSpace,
TopExtraSpace,
BottomExtraSpace;
^-- Spazi liberi (in pixel) da lasciare in alto,basso,destra e
sinistra quando le finestre vengono riaggiustate.
char **DictWord;
^-- Puntatore ad un vettore di (char *).Ogni stringa è una delle
frasi presenti nel dizionario.
int NumDictWord;
^-- Numero di parole nel dizionario.
UBYTE UseAutoCase;
^-- TRUE=Attiva autocase (aggiusta maius./minus. delle parole
presenti nel dizionario).
UBYTE CheckPar;
^-- TRUE=Attiva controllo delle parentesi '(' ')' quando il
cursore lascia la linea.
UBYTE FastMode;
^-- TRUE=Attiva modo veloce,FALSE=modo normale.
char **Ref;
^-- Puntatore ad un vettore di (char *). Ogni stringa contiene un
pattern o una directory in cui cercare i riferimenti durante
la creazione della mappa.
int NumRef;
^-- Numero di stringhe nel vettore precedente.
UBYTE RAMReference;
^-- TRUE=Mantieni la mappa dei riferimenti in RAM.
UBYTE ReferenceCase;
^-- TRUE=Ricerca dei riferimenti case-sensitive,FALSE=non case-sen.
char ReferenceFile[MAXREFNAME+1];
^-- Nome del file contenente la mappa dei riferimenti.
char **HuntPath;
^-- Puntatore ad un vettore di stringhe. Ogni stringa rappresenta
una directory in cui ricercare i file quando l'utente attiva
l'apposito comando.
int NumHuntPath;
^-- Numero di stringhe presenti nel vettore precedente.
UBYTE UseRTSysReq;
UBYTE UseRTFileReq;
UBYTE UseRTFontReq;
UBYTE UseRTScreenReq;
^-- TRUE=Usa, rispettivamente, le richieste, i file-requester,
i font-requester, e i screenmode-requester della ReqTools.library.
Ponendo a FALSE uno dei flag ProgED utilizza la Asl.library.
char **ProjectFiles;
^-- Puntatore ad un vettore di stringhe. Ogni stringa è il nome
di uno dei file nel progetto.
int NumProjectFiles;
^-- Numero di file nel progetto (numero di stringhe nel vettore
precedente).
UWORD Left,
Right;
^-- Margini sinistro e destro per le operazioni di raggruppamento
dei blocchi.
char XpkLib[5];
^-- Nome libreria XPK da utilizzare per i salvataggi con la
XpkMaster.library.
UBYTE XpkMode;
^-- Modo XPK da utilizzare per i salvataggi con la XpkMaster.library.
int XpkPos;
^-- NON MANIPOLARE!!!!!!!!!! Grazie.
char XpkPassWord[52];
^-- Password per le librerie XPK che la richiedono.
ULONG UndoLevels;
^-- Numero di livelli di UNDO. Quando ProgED apre una nuova finestra
copia questo valore nel campo UndoLevels della finestra e crea
la coda di UNDO della lunghezza data.
}
struct Line
{
char *Buffer;
^-- Testo della linea (termina con zero)
struct Line *PrevLine,
*NextLine;
^-- Puntatori alla linea precedente e successiva del testo
struct Folder *Folder;
^-- Se questa linea è chiusa in un fold questo puntatore punta
alla relativa struttura Folder (che si trova nella apposita
lista presente nella finestra).
}
struct MyTemplate
{
char Template[MAXTEMPLATE+1];
^-- Stringa che attiva questo template.
struct MyProgram *Prg;
^-- Programma interno da eseguire all'attivazione.
struct MyTemplate *NextTemplate;
^-- Puntatore alla prossima struttura della lista.
}
struct MyScan
{
BPTR SegList;
^-- Puntatore BPTR alla seglist della funzione caricata.
ULONG (* ASM ScanFunction)(RG(a0) char *,RG(a1) char *);
^-- Puntatore alla funzione assembler contenuta nella seglist
precedente (è pari all'indirizzo precedente più 4 bytes).
char ScanExtension[MAXEXTSCAN+1],
^-- Pattern AmigaDOS che individua i file su cui deve operare lo
scanner.
Name[MAXSCANNAME+1];
^-- Nome (su disco) della funzione.
struct MyScan *NextScan;
^-- Puntatore alla prossima struttura della lista.
}
struct MyProgram
{
char *String,
^-- Puntatore alla stringa del comando.
*Dir,
^-- Eventuale directory corrente (solo per TYPE_SHELL/TYPE_AREXX).
*Output;
^-- Eventuale file d'uscita (solo per TYPE_SHELL/TYPE_AREXX).
UBYTE Type;
^-- Tipo del comando (vedi costanti TYPE_xxxxx).
UBYTE Async;
^-- TRUE=comando asincrono,FALSE=sincrono. Vale solo per i
comandi di tipo TYPE_SHELL. è automaticamente TRUE per
i comandi TYPE_AREXX.
struct MyProgram *NextProgram;
^-- Puntatore al prossimo comando del programma interno.
}
struct MyMenu
{
char Name[MAXMENUNAME+1];
^-- Nome di questo menù.
struct MyItem *Items;
^-- Puntatore alla lista di item relativi a questo menù.
struct MyMenu *NextMenu;
^-- Puntatore al prossimo menù della lista.
}
struct MyItem
{
char Name[MAXMENUNAME+1];
^-- Nome di questo item.
char Key[MAXMENUNAME+1];
^-- Tasto (o stringa) di attivazione di questo item.
struct MySub *Subs;
^-- Puntatore alla lista di subitem relativi a questo menù.
struct MyProgram *Prg;
^-- Puntatore al programma interno da eseguire all'attivazione
di questo item.
UBYTE CheckType; /* NB: DEVE RIMANERE DOPO Prg */
^-- Tipo di checkmark da assegnare a questo item. Vedi costanti
CHECK_xxxx.
struct MyItem *NextItem;
^-- Puntatore al prossimo item.
}
struct MySub
{
char Name[MAXMENUNAME+1];
^-- Nome di questo subitem.
char Key[MAXMENUNAME+1];
^-- Tasto (o stringa) d'attivazione di questo subitem.
struct MyProgram *Prg;
^-- Programma interno da eseguire all'attivazione del subitem.
UBYTE CheckType; /* NB: DEVE RIMANERE DOPO Prg */
^-- Tipo di checkmark da assegnare a questo item. Vedi costanti
CHECK_xxxx.
struct MySub *NextSub;
^-- Puntatore al prossimo subitem.
}
struct MyKey
{
ULONG Qual,
Code;
^-- Identificano il tasto a cui rispondere (corrispondono ai campi
Code e Qualifier di un messaggio intuition).
struct MyProgram *Prg;
^-- Programma interno da eseguire all'attivazione del tasto.
struct MyKey *NextKey;
^-- Prossimo tasto nella lista.
}
struct Event
{
UBYTE Type;
UBYTE Arg1;
char *Arg2;
ULONG Arg3,
Arg4,
Arg5,
Arg6,
Arg7;
LONG Col,
Line;
}
^-- Questa struttura è volutamente lasciata senza commento.
struct Folder
{
char Name[MAXFOLDNAME+1];
^-- Nome assegnato dalla funzione di ricerca a questo fold (viene
mostrato sulla linea che rappresenta il fold stesso).
long Num;
^-- Numero di linee di cui è composto il fold.
struct Line *Line;
^-- Linea alla quale si trovava il cursore al momento della
chiusura.
long Col;
^-- Colonna alla quale si trovava il cursore al momento della
struct Line *Start,
*End;
^-- Linea iniziale e finale del fold.
struct Folder *NextFolder;
^-- Puntatore al prossimo fold della lista.
}
struct Marker
{
struct Line *Line;
^-- Puntatore alla linea relativa alla posizione memorizzata. Se la
linea viene cancellata ProgED porta, automaticamente, questo
valore a NULL. In questo caso un eventuale salto porta il
cursore alla prima linea del testo.
long Col;
^-- Colonna relativa alla posizione memorizzata.
}
------------
2. Scanner
------------
Uno scanner deve essere scritto tramite una funzione assembler o una
funzione C che prende gli argomenti nei registri. Il codice risultante
deve essere linkato SENZA alcun modulo di startup, in modo tale che la
prima locazione eseguibile sia l'inizio della funzione scritta. La
funzione di ricerca riceve due argomenti nei seguenti registri:
A0: Indirizzo della linea su cui effettuare la ricerca. Punta ad una
stringa terminata con 0.
A1: Indirizzo del buffer che conterrà il riferimento, se trovato.
La funzione deve ritornare nel registro D0 la lunghezza della stringa
creata nel buffer puntato da A1. Nel caso la funzione non abbia trovato
nulla deve ritornare 0.
NOTA: è necessario salvare tutti i registri all'ingresso della
funzione e ripristarli all'uscita.
-----------
3. Folder
-----------
Una funzione di ricerca dei fold deve essere scritta tramite una funzione
assembler o una funzione C che prende gli argomenti nei registri. Il codice
risultante deve essere linkato SENZA alcun modulo di startup, in modo tale
che la prima locazione eseguibile sia l'inizio della funzione scritta. La
funzione di ricerca riceve due argomenti nei seguenti registri:
A0: è l'indirizzo della struttura PEDWindow relativa al testo su
cui effettuare la ricerca.
D0: Contiene il numero della colonna su cui è posizionato il cursore.
(0=prima colonna).
D1: Contiene il numero della linea su cui è posizionato il cursore.
Tale numero è assoluto. Ciò significa che non tiene conto dei
fold eventualmente presenti nel testo. (0=prima linea).
A1: Contiene l'indirizzo di una long-word. In tale long-word la funzione
deve scrivere il numero della linea iniziale del fold, se trovato.
Anche in questo caso la funzione non deve considerare eventuali
fold già presenti nel testo. (0=prima linea).
A2: Contiene l'indirizzo di una long-word. In tale long-word la funzione
deve scrivere il numero della linea finale del fold, se trovato.
Anche in questo caso la funzione non deve considerare eventuali
fold già presenti nel testo. (0=prima linea).
A3: Punta ad un buffer in cui la funzione deve scrivere la stringa
che ProgED scriverà a fianco dell'indicatore ">FOLD". Generalmente
il nome della funzione C, ecc.
La funzione deve ritornare in D0 il valore 1 se ha trovato un fold, 0
altrimenti. Nel primo caso la funzione deve anche fornire, tramite A1 e A2
i numeri di linea iniziali e finali del fold e, tramite A3, la stringa
rappresentante il fold. è necessario,infine, salvare tutti i registri
all'ingresso della funzione e ripristinarli all'uscita.
NOTA: la funzione 'FOLD ALL' viene eseguita eseguendo una chiamata
alla funzione su tutte le linee (dalla prima all'ultima) e con il
numero di colonna pari a 0 (prima colonna).
----------------
4. Clienti API
----------------
ProgED consente ad applicazioni esterne (chiamate "clienti") di
"agganciarsi" ad esso. Un cliente API è semplicemente un normale
programma (scritto in qualsiasi linguaggio). Tale programma deve
essere scritto in modo tale da "registrarsi" presso il ProgED. Ciò
consente al ProgED di tracciare tutti i clienti e di mandar loro
messaggi sulle operazioni che devono effettuare.
I messaggi che un cliente deve inviare a ProgED (nella sua porta
API di nome "PED_API") hannno la seguente struttura:
struct APIMessage
{
struct Message am_Message;
ULONG am_MsgType,
am_MsgArg[10],
am_RC;
}
am_Message:
è un campo contenente un messaggio standard Exec.
am_MsgType:
Contiene il tipo di messaggio da inviare.
am_MsgArg[]:
è un vettore contenente un massimo di 10 argomenti
dipendenti dal tipo del messaggio
am_RC:
è il codice di ritorno che ProgED restituisce al cliente
per informarlo sul successo dell'operazione.
I tipi di messaggi che un cliente può spedire a ProgED sono, per ora:
PED_API_REGISTER:
Registra un cliente presso ProgED. Richiede un puntatore ad una
struttura di tipo APIClient in am_MsgArg[0]. Non ritorna nessun
risultato in am_RC.
PED_API_UNREGISTER:
Informa ProgED che il cliente vuole andarsene (!?). Richiede lo
STESSO puntatore dato al momento della registrazione, con il
messaggio PED_API_REGISTER, in am_MsgArg[0]. Non ritorna nessun
risultato in am_RC.
PED_API_ADD_INTERNAL_COMMAND:
Consente di espandere le funzionalità del ProgED aggiungendo un
nuovo comando interno. A tale scopo è necessario allocare e
riempire una struttura ArexxExtCmds e fornire il suo puntatore
in am_MsgArg[0]. Nessun risultato in am_RC.
PED_API_REM_INTERNAL_COMMAND:
Rimuove un comando precedentemente aggiunto tramite il messaggio
PED_API_ADD_INTERNAL_COMMAND. è necessario fornire in am_MsgArg[0]
lo STESSO puntatore dato al momento dell'aggiunta del comando.
Non ritorna risultati in am_RC.
PED_API_GET_ACTIVE_WINDOW:
Ottiene, in am_RC, l'indirizzo della struttura PEDWindow associata
alla finestra attualmente attiva.
PED_API_GET_WINDOW_LIST:
Ottiene, in am_RC, l'indirizzo iniziale della lista di strutture
PEDWindow corrispondenti ai testi in memoria.
PED_GET_SCREEN_ADDRESS:
Ottiene, in am_RC, l'indirizzo dello schermo del ProgED. Se il ProgED
è attualmente iconificato ritorna NULL.
PED_GET_PREFS_ADDRESS:
Ottiene, in am_RC, l'indirizzo della struttura Prefs.
PED_GET_PUBSCRNAME:
Ottiene, in am_RC, un puntatore al nome dello schermo pubblico
aperto dal ProgED.
NOTA: La struttura ArexxExtCmds (e tutti gli oggetti a cui puntano i
suoi campi), fornita al momento dell'aggiunta del comando, deve
rimanere valida in memoria. è possibile riutilizzarla (o
liberare la memoria associata solo DOPO aver utilizzato un
messaggio di tipo PED_REM_INTERNAL_COMMAND.
Lo stesso vale per la struttura APIClient utilizzata per il
messaggio PED_API_ADD_INTERNAL_COMMAND. In questo caso è
possibile riutilizzare la struttura dopo il corrispondente
messaggio PED_API_REM_INTERNAL_COMMAND.
I messaggi che ProgED può inviare ad un cliente sono, per ora:
PED_API_SHOW:
ProgED ha riaperto il suo schermo. L'indirizzo dello schermo
può essere ottenuto nel campo am_MsgArg[0]. Nel campo am_MsgArg[1],
invece, si trova un puntatore al nome dello schermo pubblico
utilizzato. Il cliente puo' utilizzare queste due informazioni
per aprire eventuali finestre sullo schermo del ProgED. Questo
messaggio viene spedito solo se, al momento della registrazione,
il cliente ha settato il flag NOTIFY_ON_SHOWHIDE.
PED_API_HIDE:
ProgED stà per chiudere il suo schermo. Questo messaggio viene
spedito solo se, al momento della registrazione, il cliente ha
settato il flag NOTIFY_ON_SHOWHIDE.
PED_API_KEY:
L'utente ha battuto un tasto. Il cliente può ottenere la struttura
IntuiMessage relativa leggendo il campo MsgArg[0]. Tale campo
conterrà il puntatore alla struttura IntuiMessage contenente il
messaggio di tipo rawkey ricevuto dal ProgED. Questo messaggio
viene spedito solo se, al momento della registrazione, il cliente
ha settato il flag NOTIFY_ON_KEY.
NOTA: In ogni caso, al termine della gestione di questo messaggio,
ProgED eseguirà l'azione legata al tasto. Inoltre il cliente
NON DEVE modificare il messaggio stesso, perchè è un messaggio
proveniente da Intuition!
PED_API_QUIT:
ProgED sta per terminare. Alla ricezione di questo messaggio (che
viene SEMPRE inviato a prescindere dai flag NOTIFY_xxx) il cliente
deve chiudere le eventuali finestre e terminare. E' VIETATO
UTILIZZARE LA PORTA API DOPO LA RICEZIONE DI QUESTO MESSAGGIO !!!!!
Questo implica che, dopo la ricezione di questo messaggio, il
cliente NON DEVE tentare di togliere la registrazione e/o la
definizione di comandi esterni.
Qui di seguito sono riportate le spiegazioni riguardanti i campi delle
diverse strutture utilizzate.
struct APIClient
{
struct MsgPort *ac_ClientPort;
ULONG ac_Notify;
char *ac_name;
struct APIClient *ac_Next;
}
ac_ClientPort:
Indica l'indirizzo di una porta messaggi a cui ProgED invierà i
messaggi informativi al cliente. Questo tipo di messaggi verrà
spiegato successivamente.
ac_Notify:
Indica quali tipi di messaggi il cliente vuole ricevere dal ProgED.
Gli unici tipi di messaggi selezionabili attualmente sono indicati
dal flag NOTIFY_ON_SHOW_HIDE.
ac_Name:
Punta al nome del cliente.
ac_Next:
Porre a NULL. Conterrà il successore cliente della lista interna
del ProgED.
struct ArexxExtCmds
{
UBYTE External;
char *Name;
char *Template;
void *Defaults[MAXREXXARGS];
LONG ASM (*CommFunc)( RG(a0) struct CommandData *);
struct ArexxExtCmds *NextCmd;
}
External:
Indica che il comando è gestito da un cliente. Porre SEMPRE a TRUE.
Name:
Nome del comando. Specificare sempre in lettere maiuscole.
Template:
è il template AmigaDOS del comando.
Default[]:
Indica il vettore di puntatori che deve essere passato alla
funzione ReadArgs della dos.library. Deve contenere i valori
di default dei parametri del template. Per ulteriori informazioni
leggere la documentazione della funzione ReadArgs.
CommFunc:
Indica il puntatore alla funzione che realizza il comando. Tale
funzione deve essere scritta in assembler (o ricevere i parametri
come una funzione assembler). Essa deve ricevere un puntatore ad
una struttura CommandData in A0 e ritornare il codice d'errore
risultante dall'esecuzione in D0. In seguito analizzeremo la
struttura CommandData.
NextCmd:
Porre a NULL. ProgED ne modificherà il valore portandolo a
puntare al prossimo comando fornito dallo stesso cliente o da
un altro.
struct CommandData
{
char *CommandLine;
void **CommandArgs;
struct MyWindow *CurrentWindow,
*FirstWindow;
struct Prefs *CurrentPrefs;
LONG ASM (*ExecuteInternalCommand)(RG(a0) char *);
}
CommandLine:
Punta ad una stringa riportante l'intera linea di comando riguardante
il comando.
CommandArgs:
Punta ad un vettore di (void *). Ogni puntatore deve essere utilizzato
secondo le norme dettate dalla ReadArgs. Questo vettore, infatti, è
il risultato della applicazione della stessa funzione alla linea di
comando (tenendo presente i default dati nella struttura ArexxExtCmds).
CurrentWindow:
Indica il puntatore alla struttura PEDWindow indicante la finestra
attualmente attiva.
FirstWindow:
Indica il puntatore alla prima struttura PEDWindow della lista di
finestre mantenuta dal ProgED.
ExecuteInternalCommand:
è un puntatore ad una funzione assembler. Chiamando questa
funzione (specificando in A0 il puntatore ad una stringa) è
possibile eseguire i comandi interni del ProgED. A tale scopo
la stringa puntata da A0 deve contenere la linea di comando
desiderata. In D0 viene ritornato il codice d'errore risultante.
NOTA: Non utilizzare la porta ARexx di ProgED per eseguire i
comandi interni! Così facendo, infatti, si bloccherebbero
sia ProgED che il cliente. Ciò è dovuto al fatto che, mentre
ProgED esegue la funzione che implementa il comando, NON PUò
rispondere ai messaggi provenienti da sè stesso!
-------------------
5. Funzioni utili
-------------------
Le funzioni C che seguono sono utili per la scrittura di folder e
scanner. Esse riguardano la ricerca di linee. Potete utilizzarle
tagliandole da questo testo e inserendole nei vostri programmi.
/*****
*
* FUNZIONE: struct Line *SearchLine(struct Line *line,int y)
*
* SCOPO: Cerca l'indirizzo della linea "y-esima" (0=prima) a partire
* dalla prima linea del file data da line.
* NB: Tiene conto dei FOLDS.
*
* RESTITUISCE: Un puntatore alla linea cercata.
*
****/
struct Line *SearchLine(struct Line *line,int y)
{
while(((y--)>0)&&(line)) line=NextLine(line);
return(line);
}
/*****
*
* FUNZIONE: int SearchLine2(struct Line *line,int y)
*
* SCOPO: Cerca il # della linea (tenendo conto dei FOLD)
* della linea ASSOLUTA y.
*
* RESTITUISCE: Il # della linea cercata.
*
****/
int SearchLine2(struct Line *line,int y)
{
int n=0;
while(((y--)>0)&&(line))
{
if (!line->Folder) n++;
else if (line->NextLine)
if (!line->NextLine->Folder) n++;
line=line->NextLine;
}
if (line) return(n);
else return(0);
}
/*****
*
* FUNZIONE: int SearchLine3(struct Line *first,struct Line *line)
*
* SCOPO: Cerca il # assoluto della linea line a partire
* dalla prima linea del file data da first.
* NB: NON tiene conto dei FOLDS.
*
* RESTITUISCE: Il # della linea cercata.
*
****/
int SearchLine3(struct Line *first,struct Line *line)
{
long n=0;
while(first)
{
if (first==line) break;
n++;
first=first->NextLine;
}
return(n);
}
/*****
*
* FUNZIONE: struct Line *SearchLine4(struct Line *line,int y)
*
* SCOPO: Cerca l'indirizzo della linea "y-esima" (0=prima) a partire
* dalla prima linea del file data da line.
* NB: NON tiene conto dei FOLDS.
*
* RESTITUISCE: Un puntatore alla linea cercata.
*
****/
struct Line *SearchLine4(struct Line *line,int y)
{
while(((y--)>0)&&(line)) line=line->NextLine;
return(line);
}